<HTML>
<BODY>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->

<B><A HREF="RANDOM.html">RANDOM(3)</A></B>	       FreeBSD Library Functions Manual 	     <B><A HREF="RANDOM.html">RANDOM(3)</A></B>


</PRE>
<H2>NAME</H2><PRE>
     <B>random</B>, <B>srandom</B>, <B>srandomdev</B>, <B>initstate</B>, <B>setstate</B> - better random number
     generator; routines for changing generators


</PRE>
<H2>SYNOPSIS</H2><PRE>
     <B>#include</B> <B>&lt;stdlib.h&gt;</B>

     <I>long</I>
     <B>random</B>(<I>void</I>)

     <I>void</I>
     <B>srandom</B>(<I>unsigned</I> <I>long</I> <I>seed</I>)

     <I>void</I>
     <B>srandomdev</B>(<I>void</I>)

     <I>char</I> <I>*</I>
     <B>initstate</B>(<I>unsigned</I> <I>long</I> <I>seed</I>, <I>char</I> <I>*state</I>, <I>long</I> <I>n</I>)

     <I>char</I> <I>*</I>
     <B>setstate</B>(<I>char</I> <I>*state</I>)


</PRE>
<H2>DESCRIPTION</H2><PRE>
     The <B>random</B>() function uses a non-linear additive feedback random number
     generator employing a default table of size 31 long integers to return
     successive pseudo-random numbers in the range from 0 to (2**31)-1.  The
     period of this random number generator is very large, approximately
     16*((2**31)-1).

     The <B>random</B>() and <B>srandom</B>() functions have (almost) the same calling se-
     quence and initialization properties as the <B><A HREF="rand.html">rand(3)</A></B> and <B><A HREF="rand.html">srand(3)</A></B> func-
     tions.  The difference is that <B><A HREF="rand.html">rand(3)</A></B> produces a much less random se-
     quence -- in fact, the low dozen bits generated by rand go through a
     cyclic pattern.  All the bits generated by <B>random</B>() are usable.  For ex-
     ample, `random()&amp;01' will produce a random binary value.

     Like <B><A HREF="rand.html">rand(3)</A></B>,  <B>random</B>() will by default produce a sequence of numbers
     that can be duplicated by calling <B>srandom</B>() with `1' as the seed.

     The <B>srandomdev</B>() routine initialize a state array using <B><A HREF="urandom.html">urandom(4)</A></B> random
     number device which returns good random numbers, suitable for crypto-
     graphic use.  Note that this particular seeding procedure can generate
     states which are impossible to reproduce by calling <B>srandom</B>() with any
     value, since the succeeding terms in the state buffer are no longer de-
     rived from the LC algorithm applied to a fixed seed.

     The <B>initstate</B>() routine allows a state array, passed in as an argument,
     to be initialized for future use.	The size of the state array (in bytes)
     is used by <B>initstate</B>() to decide how sophisticated a random number gener-
     ator it should use -- the more state, the better the random numbers will
     be.  (Current "optimal" values for the amount of state information are 8,
     32, 64, 128, and 256 bytes; other amounts will be rounded down to the
     nearest known amount.  Using less than 8 bytes will cause an error.)  The
     seed for the initialization (which specifies a starting point for the
     random number sequence, and provides for restarting at the same point) is
     also an argument.	The <B>initstate</B>() function returns a pointer to the pre-
     vious state information array.

     Once a state has been initialized, the <B>setstate</B>() routine provides for
     rapid switching between states.  The <B>setstate</B>() function returns a point-
     er to the previous state array; its argument state array is used for fur-
     ther random number generation until the next call to <B>initstate</B>() or
     <B>setstate</B>().

     Once a state array has been initialized, it may be restarted at a differ-
     ent point either by calling <B>initstate</B>() (with the desired seed, the state
     array, and its size) or by calling both <B>setstate</B>() (with the state array)
     and <B>srandom</B>() (with the desired seed).  The advantage of calling both
     <B>setstate</B>() and <B>srandom</B>() is that the size of the state array does not
     have to be remembered after it is initialized.

     With 256 bytes of state information, the period of the random number gen-
     erator is greater than 2**69 which should be sufficient for most purpos-
     es.


</PRE>
<H2>AUTHORS</H2><PRE>
     Earl T. Cohen


</PRE>
<H2>DIAGNOSTICS</H2><PRE>
     If <B>initstate</B>() is called with less than 8 bytes of state information, or
     if <B>setstate</B>() detects that the state information has been garbled, error
     messages are printed on the standard error output.


</PRE>
<H2>SEE ALSO</H2><PRE>
     <B><A HREF="rand.html">rand(3)</A></B>,  <B><A HREF="rand.html">srand(3)</A></B>,  <B><A HREF="urandom.html">urandom(4)</A></B>


</PRE>
<H2>HISTORY</H2><PRE>
     These functions appeared in 4.2BSD.


</PRE>
<H2>BUGS</H2><PRE>
     About 2/3 the speed of <B><A HREF="rand.html">rand(3)</A></B>.

     The historical implementation used to have a very weak seeding; the ran-
     dom sequence did not vary much with the seed.  The current implementation
     employs a better pseudo-random number generator for the initial state
     calculation.

4.2 Berkeley Distribution	 June 4, 1993				     2
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
